The section describes the programming interface of the ADC Peripheral driver. More...

Data Structures
struct	adc_calibration_param_t
	Defines the calibration parameter structure. More...

struct	adc_user_config_t
	Defines the ADC basic configuration structure. More...

struct	adc_extend_config_t
	Defines the ADC extended configuration structure. More...

struct	adc_channel_config_t
	Defines the channel configuration structure. More...

Typedefs
typedef void(*	adc_isr_callback_t )(void)
	Defines the ADC ISR callback function. More...

Functions
adc_status_t	adc_get_calibration_param (uint32_t instance, adc_calibration_param_t *paramPtr)
	Gets the parameters for calibration. More...

adc_status_t	adc_set_calibration_param (uint32_t instance, adc_calibration_param_t *paramPtr)
	Sets the parameters for calibration. More...

adc_status_t	adc_auto_calibration (uint32_t instance, adc_calibration_param_t *paramPtr)
	Executes the auto calibration. More...

adc_status_t	adc_init (uint32_t instance, adc_user_config_t *cfgPtr)
	Initializes the ADC with the basic configuration. More...

adc_status_t	adc_init_extend (uint32_t instance, adc_extend_config_t *extendCfgPtr)
	Initializes the ADC with the extended configurations when necessary. More...

void	adc_shutdown (uint32_t instance)
	Shuts down the ADC. More...

adc_status_t	adc_start_conversion (uint32_t instance, adc_channel_config_t *channelCfgPtr)
	Starts the conversion from the indicated channel. More...

adc_status_t	adc_stop_conversion (uint32_t instance, adc_channel_config_t *channelCfgPtr)
	Stops the conversion. More...

bool	adc_is_conversion_completed (uint32_t instance, adc_channel_config_t *channelCfgPtr)
	Checks whether the conversion is completed. More...

uint32_t	adc_get_conversion_value (uint32_t instance, adc_channel_config_t *channelCfgPtr)
	Gets the value after the conversion. More...

void	adc_register_user_callback_isr (uint32_t instance, adc_isr_callback_t func)
	Registers the custom callback function of the ADC ISR. More...

ADC peripheral driver

Overview

The ADC peripheral driver configures the ADC (Analog-to-Digital Converter). It handles calibration, initialization and configuration of ADC module.

Initialization

To initialize the ADC module, call adc_init() and pass the configuration data structure. This function automatically enables the ADC module and clock. When working with advanced features, call adc_init_extend() additionally and pass the extended configuration data structure. This function enables the extended features, such as the hardware trigger, hardware average, hardware compare, low power mode, and high speed mode.

Model building

Multiple channels share the converter, which can only serve one channel at a time. As a result the ADC channel is considered as an attribute when configuring the ADC converter instance. Therefore, when you obtain the ADC value, the value comes with the converter, after the channel is set as expected. ADC can work in three modes: Interrupt mode, Polling mode, and DMA mode. Interrupt is the recommended mode where the conversion value buffer is updated by ADC ISR. The polling mode polls the complete flag before obtaining the conversion value. The DMA mode needs the DMA support.

Call diagram

To use the ADC driver, the user should follow these steps:

Execute adc_auto_calibration() to calibrate the ADC device if no other indicated offset values are used.
Initialize the ADC converter by calling the adc_init().
Initialize the advanced feature for ADC converter by calling the adc_init_extend() as needed.
Register the user-defined callback to ADC ISR by calling adc_register_user_callback_isr() as needed. The callback function is executed when the ADC interrupt occurs.
Set or reset the expected channel to a converter and execute the conversion by calling the adc_start_convertion().
Obtain the ADC value by calling the adc_get_conversion_value().
Pause the converter by calling the adc_stop_conversion() as needed.
Shut down the converter by calling the adc_shutdown().

This is an example code to initialize and configure the ADC driver in interrupt mode:

uint32_t val;
// Define the ADC calibration parameter variable.
adc_calibration_param_t myAdcCalParam;
// Define the ADC converter basically. 
adc_user_config_t myAdcUserCfg = 
{
    .clockSourceMode        = kAdcClockSourceAsynchrounous,  // Use the ADC asynchronous clock when converting.
    .clockSourceDividerMode = kAdcClockDivider8,             // Set the clock divider from the bus clock.
    .resolutionMode         = kAdcSingleDiff16,              // Conversion resolution.
    .referenceVoltageMode   = kAdcVoltageVref,               // Reference voltage.
    .isContinuousEnabled    = true                           // Enable continuous work.
};
// Define the ADC channel.
adc_channel_config_t myAdcChannelCfg = 
{
    .channelId              = kAdcChannelTemperature,        // Set the channel ID.
    .isDifferentialEnabled  = false,                         // Use single end channel.
    .isInterruptEnabled     = true,                          // Use interrupt mode.
    .groupMux               = kAdcChannelMuxA                // Set the group Mux.
};
// Define the ADC converter for advanced features.
adc_extend_config_t myAdcExtendCfg =
{
    .isLowPowerEnabled      = false,                         // Disable the low power mode.
    .isLongSampleEnabled    = true,                          // Enable the long sample.
    .hwLongSampleMode       = kAdcLongSampleDefault,         // Set the long sample mode.
    .isHighSpeedEnabled     = false,                         // Disable the high speed mode.
    .isAsynClockEnabled     = true,                          // Enable the ADC asynchronous clock when initialized.
    .isHwTriggerEnabled     = false,                         // Disable the hardware trigger.
    .isHwCompareEnabled     = false,                         // Disable the hardware compare.
    .isHwCompareGreaterEnabled = false,                      // Hardware compare related.
    .isHwCompareRangeEnabled= false,                         // Hardware compare related.
    .hwCompareValue1        = 0,                             // Hardware compare related.
    .hwCompareValue2        = 0,                             // Hardware compare related.
    .isHwAverageEnabled     = true,                          // Enable the hardware average.
    .hwAverageSampleMode    = kAdcHwAverageCount32,          // Hardware average related.
    .isDmaEnabled           = false                          // Disable the DMA switcher.
};
// Execute the auto calibration before use ADC.
adc_auto_calibration(0U, &myAdcCalParam)
// Initialize the ADC converter basically.
adc_init(0U, &myAdcUserCfg);
// Initialize the ADC additionally for extend features.
adc_init_extend(0U, &myAdcExtendCfg);
// Set the ADC channel and start conversion.
adc_start_conversion(0U, &myAdcChannelCfg);
// Get the ADC value.
val = adc_get_conversion_value(0U, &myAdcChannelCfg);
// ...
// Pause the converter.
adc_stop_conversion(0U, &myAdcChannelCfg);
// ...
// Shut down the ADC converter.
adc_shutdown(0U);

Data Structure Documentation

struct adc_calibration_param_t

This structure keeps the calibration parameter after executing the auto-calibration or filled by indicated ones.

Data Fields
uint32_t	PG
	The value for PG register.

uint32_t	MG
	The value for MG register.

struct adc_user_config_t

This structure is used when initializing the ADC device associated with adc_init(). It contains the basic feature configuration which are necessary.

Data Fields
adc_clock_source_mode_t	clockSourceMode
	Selection of ADC clock source.

adc_clock_divider_mode_t	clockSourceDividerMode
	Selection of ADC clock divider.

adc_resolution_mode_t	resolutionMode
	Selection of ADC resolution.

adc_reference_voltage_mode_t	referenceVoltageMode
	Selection of ref voltage source.

bool	isContinuousEnabled
	Switcher to enable continuous conversion.

struct adc_extend_config_t

This structure is used when initializing the ADC device associated with adc_init_extend(). It contains the advanced feature configuration when necessary.

Data Fields
bool	isLowPowerEnabled
	Switcher to enable the low power mode.

bool	isLongSampleEnabled
	Switcher to enable the long sample mode.

adc_long_sample_mode_t	hwLongSampleMode
	Selection of long sample mode.

bool	isHighSpeedEnabled
	Switcher to enable high speed sample mode.

bool	isAsynClockEnabled
	Switcher to enable internal asynchronous clock at initialization.

bool	isHwTriggerEnabled
	Switcher to enable hardware trigger.

bool	isHwCompareEnabled
	Switcher to enable hardware compare.

bool	isHwCompareGreaterEnabled
	Switcher to enable greater compare.

bool	isHwCompareRangeEnabled
	Switcher to enable range compare.

uint32_t	hwCompareValue1
	Low limit in hardware compare.

uint32_t	hwCompareValue2
	High limit in hardware compare.

bool	isHwAverageEnabled
	Switcher to enable hardware average.

adc_hw_average_mode_t	hwAverageSampleMode
	Selection of hardware average time.

bool	isDmaEnabled

struct adc_channel_config_t

This structure is used when setting the conversion channel associated with adc_start_conversion(), adc_stop_conversion(), adc_is_conversion_completed() and adc_get_conversion_value(). It contains all the information that can identify an ADC channel.

Data Fields
adc_channel_mode_t	channelId
	Channel number.

bool	isDifferentialEnabled
	The switcher to enable differential channel.

bool	isInterruptEnabled
	The switcher to enable interrupt when conversion is completed.

adc_group_mux_mode_t	muxSelect
	Selection mux to group A(0) or group B(1)

Typedef Documentation

typedef void(* adc_isr_callback_t)(void)

This type defines the prototype of ADC ISR callback function that can be registered inside the ISR.

Function Documentation

adc_status_t adc_get_calibration_param	(	uint32_t	instance,
		adc_calibration_param_t *	paramPtr
	)

This function is used to get the calibration parameters in auto-calibrate mode. Execute this function to obtain the parameter for the calibration during the initialization. This process may be time consuming.

Parameters

instance	ADC instance ID.
paramPtr	The pointer to a empty calibration parameter structure.

Returns: The execution status.

adc_status_t adc_set_calibration_param	(	uint32_t	instance,
		adc_calibration_param_t *	paramPtr
	)

This function is used to set the calibration parameters. The parameters can be generated from the auto-calibration by the adc_get_calibration_param() or created by manually indicated parameters.

Parameters

instance	ADC instance ID.
paramPtr	The pointer to a filled calibration parameter structure.

Returns: The execution status.

adc_status_t adc_auto_calibration	(	uint32_t	instance,
		adc_calibration_param_t *	paramPtr
	)

This function is used to execute the auto calibration. Recommended configuration has been accepted to fetch calibration parameters for highest accuracy. The calibration offset is returned to the application for further use. After the auto calibration process, the initialization function should be called explicitly to update the configuration according to the application.

Parameters

instance	ADC instance ID.
paramPtr	The pointer to an empty calibration parameter structure. It is filled with the calibration offset value after the function is called.

Returns: The execution status.

adc_status_t adc_init	(	uint32_t	instance,
		adc_user_config_t *	cfgPtr
	)

This function ensures that the basic operations of ADC function correctly. This function should be called when an application does not require complex features.

Parameters

instance	ADC instance ID.
cfgPtr	The pointer to basic configuration structure.

Returns: The execution status.

adc_status_t adc_init_extend	(	uint32_t	instance,
		adc_extend_config_t *	extendCfgPtr
	)

This function provides advanced features according when an application requires complex configurations. They are: low power mode, long sample mode, high speed mode, asynchronous work mode, hardware trigger, hardware compare, and hardware average.

Parameters

instance	ADC instance ID.
extendCfgPtr	The pointer to extend configuration structure.

Returns: The execution status.

void adc_shutdown ( uint32_t instance )

Shutting down the ADC cuts off the clock to the indicated ADC device.

Parameters

instance ADC instance ID.

adc_status_t adc_start_conversion	(	uint32_t	instance,
		adc_channel_config_t *	channelCfgPtr
	)

Triggers the indicated channel conversion in a single conversion mode. This function should be called when each time the conversion is triggered. In a continuous conversion mode, this function can be called only once at the beginning of conversion. The ADC executes the conversion periodically and automatically.

Parameters

instance	ADC instance ID.
channelCfgPtr	The pointer to channel configuration structure.

Returns: The execution status.

adc_status_t adc_stop_conversion	(	uint32_t	instance,
		adc_channel_config_t *	channelCfgPtr
	)

Stops the ADC conversion. This function sets ADC to a "NULL" channel, which stops ADC conversion from any channel. It is a different function than the adc_shutdown().

Parameters

instance	ADC instance ID.
channelCfgPtr	The pointer to channel configuration structure.

Returns: The execution status.

bool adc_is_conversion_completed	(	uint32_t	instance,
		adc_channel_config_t *	channelCfgPtr
	)

Checks whether the current conversion is completed. Because there are multiple channels sharing the same converter, the status is used to indicate the converter status.

Parameters

instance	ADC instance ID.
channelCfgPtr	The pointer to channel configuration structure.

Returns: True if the event is asserted.

uint32_t adc_get_conversion_value	(	uint32_t	instance,
		adc_channel_config_t *	channelCfgPtr
	)

The value comes from the value register that may be eventually processed according to the application. When using polling mode, the value is obtained after the conversion is completed. When using the interrupt mode, the value comes from the buffer that is updated by the ADC ISR.

Parameters

instance	ADC instance ID.
channelCfgPtr	The pointer to channel configuration structure.

Returns: the value of conversion.

void adc_register_user_callback_isr	(	uint32_t	instance,
		adc_isr_callback_t	func
	)

Callback provides a friendly API for application to program the ISR. A special function needs to be executed at the moment conversion is completed and can be inserted to the ISR by calling the function registered by the user.

Parameters

instance	ADC instance ID.
func	The pointer to user indicating callback function.

Data Structures

Typedefs

Functions

ADC peripheral driver

Overview

Initialization

Model building

Call diagram

Data Structure Documentation

Data Fields

Data Fields

Data Fields

Data Fields

Typedef Documentation

Function Documentation